Skip to content

docs(skills): add vessel-file-relay skill for moving files to a vessel's host - #1

Closed
Freudator86 wants to merge 2 commits into
mainfrom
fm/vessel-file-relay-skill
Closed

docs(skills): add vessel-file-relay skill for moving files to a vessel's host#1
Freudator86 wants to merge 2 commits into
mainfrom
fm/vessel-file-relay-skill

Conversation

@Freudator86

@Freudator86 Freudator86 commented Aug 20, 2026

Copy link
Copy Markdown
Owner

Intent

Capture, as a new agent-only firstmate skill, the procedure firstmate ran five times by hand in one session: getting a local file from the captain's own machine onto a fleet vessel's host, and telling that vessel about it correctly. Bridge (coditan-bridge) is text-only and cannot carry a file's bytes, so the established pattern is a direct SSH push to the target vessel's own host, verification there, then a Bridge notice describing what landed. Secrets split off into a much stricter sub-procedure.

Deliberate decisions the captain and this brief already made, which should not be re-litigated as findings:

  • The skill file is .agents/skills/vessel-file-relay/SKILL.md, agent-only (user-invocable: false, metadata.internal: true), following the frontmatter and structure pattern of .agents/skills/stuck-crewmate-recovery/SKILL.md. .claude/skills is a symlink to .agents/skills, so one file serves both surfaces and no second copy is wanted.
  • AGENTS.md gets EXACTLY ONE new trigger line in section 13's agent-only skill list and deliberately no restated procedure content, per firstmate-coding-guidelines' inline-stub pattern and one-owner rule. The absence of procedure detail in AGENTS.md is intentional, not an omission.
  • The skill deliberately cross-references rather than restates two existing owners: coditan-bridge's docs/envelope-format.md owns the secret-request/secret-ready schema, and fleet/doctrine/credential-store-boundary.md section 7 owns the fingerprint recipe and its trailing-newline trap. Restating either would create the drift the one-owner rule forbids, so the pointers are correct as written.
  • Specific real mechanics were requested over vague paraphrase, including the exact single-shell-call clipboard capture (powershell.exe Get-Clipboard -Raw in a WSL session, piped into ssh with umask 077 and chmod 600, then unset), the root-owned mode-600 /root/.pending-secrets/ staging path, and the structural verification by size, line count, and grep -q on non-secret field labels only. Concrete dated incidents (the 2026-08-20 wrong-clipboard capture, the /opt/docs convention reuse on hlr-web-1) are load-bearing evidence and were asked for by name.
  • Section 3 documents Claude Code's Auto Mode semantic safety classifier refusing the SSH-write-of-secret step twice, that neither chat approval nor a broad Bash(ssh *) permissions.allow rule clears it, that the agent cannot self-grant via .claude/settings.local.json autoMode.allow (correctly so), and that the only route through is the captain switching the session out of Auto Mode. This is documentation of an encountered obstacle, not an instruction to bypass a security control.

Repo style rules that apply: one full sentence per line in tracked Markdown, plain dash never an em dash, no agent name as commit co-author. tests/fm-instruction-owners.test.sh enforces the skill frontmatter and section 13 trigger floor and passes. This change is documentation only: no shell scripts, no code, no behavior change.

What Changed

  • Added .agents/skills/vessel-file-relay/SKILL.md, an agent-only skill (user-invocable: false, metadata.internal: true) documenting the direct-SSH-push procedure for getting a file from the captain's machine onto a fleet vessel's host, since Bridge (coditan-bridge) is text-only and cannot carry file bytes.
  • The skill covers the plain-document push (destination convention discovery, byte-size verification, Bridge status/reply notice), the stricter secret sub-procedure (single-shell-call clipboard capture that never prints the value, root-owned mode-600 staging under /root/.pending-secrets/, structural-only verification by size/line-count/field-label grep), and Claude Code's Auto Mode classifier refusing the SSH-write-of-secret step.
  • The skill cross-references, rather than restates, the existing owners for the secret-request/secret-ready schema (coditan-bridge's docs/envelope-format.md) and the fingerprint recipe (fleet/doctrine/credential-store-boundary.md section 7).
  • Added exactly one new trigger line to AGENTS.md section 13's agent-only skill list, with no restated procedure content.

Risk Assessment

✅ Low: Documentation-only addition of one agent-only skill file plus a single AGENTS.md trigger line; content matches every deliberate decision in the user intent, satisfies the generic section-13/frontmatter floor test in tests/fm-instruction-owners.test.sh by inspection, and its cross-references to coditan-bridge's envelope-format.md and fleet/doctrine/credential-store-boundary.md section 7 are accurate to the latter's actual content.

Testing

Ran the targeted enforcing test (tests/fm-instruction-owners.test.sh), which passed all 14 assertions including the specific check for this new skill's frontmatter and AGENTS.md trigger; supplemented with manual verification of the documentation-only diff against every required/forbidden constraint in the user intent (frontmatter pattern match, single AGENTS.md trigger with no restated procedure, cross-references to real external owners, dash-not-em-dash and one-sentence-per-line style, no agent co-author), all of which held. No code or UI surface exists to exercise since this is a pure documentation change; no findings.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

⚠️ **Rebase** - 1 warning

Push main to origin, or rebase your branch onto origin/main, before gating.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

  • bash tests/fm-instruction-owners.test.sh — all 14 assertions pass (exit 0), including the 'new internal skills have one precise AGENTS.md trigger each' check that gates this skill's frontmatter and its single section 13 trigger line
  • Manual diff review of .agents/skills/vessel-file-relay/SKILL.md (127 lines) and the one added AGENTS.md line for compliance with user intent: frontmatter matches stuck-crewmate-recovery/SKILL.md's pattern (name/description/user-invocable: false/metadata.internal: true), only one AGENTS.md line was added with no restated procedure content
  • grep for em-dash characters in the new file and AGENTS.md diff — none found, only plain dashes used
  • git show -s --format=%B HEAD | grep -i co-authored — confirmed no agent name listed as commit co-author
  • Line-by-line scan for multi-sentence lines in the new SKILL.md (excluding code blocks and numbered headings) — none found, consistent with the one-full-sentence-per-line rule
  • Verified the cross-referenced owning files exist elsewhere in the fleet layout: coditan-bridge's docs/envelope-format.md project and fleet/doctrine/credential-store-boundary.md (found under /home/captain/firstmate-upstream and /home/captain/sc1-firstmate), confirming the skill correctly points to real owners instead of restating their content
✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

@allesknut-ci
Add vessel-file-relay skill for moving files to a vessel's host
ab1c902 
Bridge cannot carry a file's bytes, so a document or credential reaches a
vessel by a direct SSH push to its own host followed by a Bridge notice
describing what landed. That procedure was run five times by hand in one
session and existed nowhere in writing.

The new agent-only skill covers the plain-document push (destination
convention discovery, byte-size verification, status/reply notice), the
stricter secret path (single-call capture that never prints the value,
root-owned mode-600 staging, mandatory structural verification by size,
line count and field labels only, and the secret-request/secret-ready
envelope), and Claude Code's Auto Mode classifier refusal, which chat
approval and a broad ssh permission rule both fail to clear.

The schema and fingerprint recipe stay with their existing owners in
coditan-bridge and fleet/doctrine/credential-store-boundary.md; AGENTS.md
gets only the section 13 trigger line.
@Freudator86
Freudator86 force-pushed the fm/vessel-file-relay-skill branch from 783bcb0 to ab1c902 Compare August 20, 2026 11:20
@Freudator86

Freudator86 commented Aug 20, 2026

Copy link
Copy Markdown
Owner Author

Closing: this PR landed on the wrong repository.

The work belongs to Freudator86/admiralty, which is the fleet repository. It was authored in a checkout whose origin is admiralty, but a stale no-mistakes routing config pushed the branch here instead, and the pipeline rebased the commit onto this repo's unrelated history to do it.

No defect in the change itself - checks passed 13/13 - and nothing here was merged. It is being re-landed against Freudator86/admiralty through that repo's normal no-mistakes path, and the routing config is being corrected so this does not recur.

The branch fm/vessel-file-relay-skill is being deleted from this repository as part of the same cleanup.

@Freudator86
Freudator86 deleted the fm/vessel-file-relay-skill branch August 20, 2026 16:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Freudator86 @allesknut-ci